Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EOAdaptorContext

Inherits From:	NSObject

Declared In:	eoaccess/EOAdaptorContext.h

Class Description

An EOAdaptorContext represents a single transaction scope (logical user) on the database server to which its EOAdaptor object is connected. If the server supports multiple concurrent transaction sessions, the EOAdaptor may have several adaptor contexts. An EOAdaptorContext may in turn have several EOAdaptorChannels, which handle actual access to the data on the server. An EOAdaptorContext by default has no EOAdaptorChannels; to create a new channel send your EOAdaptorContext a createAdaptorChannel message.

Note:  When you use multiple EOAdaptorContexts, you can have several transactions occurring simultaneously on the database server. You should be aware of the issues involved in concurrent access if you do this.

Controlling Transactions

EOAdaptorContext defines a simple set of messages for explicitly controlling transactions: beginTransaction, commitTransaction, and rollbackTransaction. Each of these messages confirms the requested action with the adaptor context's delegate, then performs the action if possible. There's also a set of messages for notifying an adaptor context that a transaction has been started, committed, or rolled back by something else, such as another object, a stored procedure in the server, and so on. You use these notification messages to keep an adaptor context synchronized with the state of the server: transactionDidBegin, transactionDidCommit, and transactionDidRollback (these methods don't notify the delegate).

Notifying the Adaptor Context's Delegate

The transaction-controlling methodsÐbeginTransaction, commitTransaction, and rollbackTransactionÐnotify the adaptor context's delegate before and after a transaction operation is performed. The delegate needs only to implement a method to receive notification. The ªbeforeº messages ask the delegate if it's all right to continue with the requested operation, sending an adaptorContextWillBegin:, adaptorContextWillCommit:, or an adaptorContextWillRollback: message. The return type of each of these messages is EODelegateResponse, which allows the delegate to approve, reject, or override the transaction operation requested. An adaptor context interprets the return value of a delegate message as follows:

Return Value	Interpretation

EODelegateRejects	Abort the requested operation and return a failure result.

EODelegateApproves	Continue the requested operation and return an appropriate result

EODelegateOverrides	Do nothing, but return a success result.

When a delegate overrides an operation, it's responsible for ensuring that the result of that operation is achieved. For example, if the delegate returns EODelegateOverrides from an adaptorContextWillBegin: message, it must see itself that a transaction actually does begin.

Instance Variables

None declared in this class.

Method Types

Getting the adaptor	- adaptor

Creating a new channel	- createAdaptorChannel

Finding open channels	- hasBusyChannels

Controlling transactions	- beginTransaction
- commitTransaction
- rollbackTransaction

Notifying of other transactions	- transactionDidBegin
- transactionDidCommit
- transactionDidRollback

Nesting transactions	- canNestTransactions
- transactionNestingLevel

Setting the delegate	- setDelegate:
- delegate

Instance Methods

adaptor

- (EOAdaptor *)adaptor

Returns the EOAdaptorContext's EOAdaptor.

beginTransaction

- (BOOL)beginTransaction

Attempts to begin a new transaction, nested within the current one if nested transactions are supported. Returns YES if successful and NO if not (specifically, if nested transactions aren't supported or the delegate refuses).

This method invokes the delegate methods adaptorContextWillBegin: and adaptorContextDidBegin:.

See also:  - transactionDidBegin, - commitTransaction, - rollbackTransaction, - canNestTransactions

canNestTransactions

- (BOOL)canNestTransactions

Returns YES if the database server and the adaptor context can nest transactions, NO otherwise.

commitTransaction

- (BOOL)commitTransaction

Attempts to commit the last transaction begun, returning YES if successful. commitTransaction will return NO if:

·	a transaction is not open
·	fetches are in progress
·	the delegate returns EODelegateRejects in adaptorContextWillCommit
·	the database server fails to commit (and may rollback)

In the first three cases, the transaction is not rolled back.  In the fourth, it is.  There is no way to tell which case caused commitTransaction to return NO.

This method invokes the delegate methods adaptorContextWillCommit: and adaptorContextDidCommit:.

See also:  - transactionDidCommit, - beginTransaction, - rollbackTransaction

createAdaptorChannel

- (EOAdaptorChannel *)createAdaptorChannel

Returns a new EOAdaptorChannel, or nil if a new channel cannot be created. The newly created channel retains its context.

delegate

- delegate

Returns the adaptor context's delegate. A subclass of EOAdaptorContext doesn't need to override this method.

hasBusyChannels

- (BOOL)hasBusyChannels

Returns YES if any of the receiver's channels have outstanding operations (that is, have a fetch in progress), NO otherwise.

See also:  - isFetchInProgress (EOAdaptorChannel)

rollbackTransaction

- (BOOL)rollbackTransaction

Attempts to roll back the last transaction begun, returning YES if successful and NO if not. This method invokes the delegate methods adaptorContextWillRollback: and adaptorContextDidRollback:.

See also:  - transactionDidRollback, - beginTransaction, - commitTransaction

setDelegate:

- (void)setDelegate:anObject

Sets the adaptor context's delegate to anObject and retains it. A subclass of EOAdaptorContext doesn't need to override this method.

transactionDidBegin

- (void)transactionDidBegin

Informs the adaptor context that the server has begun a transaction, so that it can update its state to reflect this fact. Your application should invoke this method whenever it begins a transaction other than by sending a beginTransaction message (for example, by using EOAdaptorChannel's evaluateExpression:).

This method doesn't send any messages to the delegate; you should explicitly notify the delegate if necessary.

transactionDidCommit

- (void)transactionDidCommit

Informs the receiver that the server has committed a transaction, so that it can update its state to reflect this fact. Your application should invoke this method whenever it commits a transaction other than by sending a commitTransaction message (for example, by using EOAdaptorChannel's evaluateExpression:).

This method doesn't send any messages to the delegate; you should explicitly notify the delegate if necessary.

transactionDidRollback

- (void)transactionDidRollback

Informs the receiver that the server has rolled back a transaction, so that it can update its state to reflect this fact. Your application should invoke this method whenever it rolls back a transaction other than by sending a rollbackTransaction message (for example, by using EOAdaptorChannel's evaluateExpression:).

This method doesn't send any messages to the delegate; you should explicitly notify the delegate if necessary.

transactionNestingLevel

- (unsigned int)transactionNestingLevel

Returns the number of transactions in progress. If the database server and the adaptor support nested transactions, this number may be greater than 1.

Methods Implemented by the Delegate

adaptorContextDidBegin:

- (void)adaptorContextDidBegin:context

Invoked from beginTransaction to tell the delegate that context has begun a transaction. The delegate may take whatever action it needs based on this information.

adaptorContextDidCommit:

- (void)adaptorContextDidCommit:context

Invoked from commitTransaction to tell the delegate that context has committed a transaction. The delegate may take whatever action it needs based on this information.

adaptorContextDidRollback:

- (void)adaptorContextDidRollback:context

Invoked from rollbackTransaction to tell the delegate that context has rolled back a transaction. The delegate may take whatever action it needs based on this information.

adaptorContextWillBegin:

- (EODelegateResponse)adaptorContextWillBegin:context

Invoked from beginTransaction to tell the delegate that context is starting a transaction. See ªNotifying the Adaptor Context's Delegateº in the class description for an explanation of the possible return values.

adaptorContextWillCommit:

- (EODelegateResponse)adaptorContextWillCommit:context

Invoked from commitTransaction to tell the delegate that context is committing a transaction. See ªNotifying the Adaptor Context's Delegateº in the class description for an explanation of the possible return values.

adaptorContextWillRollback:

- (EODelegateResponse)adaptorContextWillRollback:context

Invoked from rollbackTransaction to tell the delegate that context is rolling back a transaction. See ªNotifying the Adaptor Context's Delegateº in the class description for an explanation of the possible return values.